home *** CD-ROM | disk | FTP | other *** search
/ Risc World 3 / Risc World 3.iso / SOFTWARE / ISSUE4 / ZAP / !Zap / Modules / !ZapMJE / !Help next >
Text File  |  2002-09-18  |  17KB  |  437 lines

  1. ZapMJE 0.80 help file
  2. © Martin Ebourne, 1997 - 1999
  3. © Zap Developers, 2000 - 2002
  4.  
  5.    This program is free software; you can redistribute it and/or modify
  6.    it under the terms of the GNU General Public License as published by
  7.    the Free Software Foundation; either version 2 of the License, or
  8.    (at your option) any later version.
  9.  
  10.    This program is distributed in the hope that it will be useful,
  11.    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12.    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13.    GNU General Public License for more details.
  14.  
  15.    You should have received a copy of the GNU General Public License
  16.    along with this program; if not, write to the Free Software
  17.    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  18.  
  19. The General Public License is included as !ZapMJE.Copying. Source is available
  20. via CVS; see <http://zap.tartarus.org/cvs> for more information.
  21.  
  22.  
  23.  
  24. Introduction
  25. ============
  26.  
  27. ZapMJE provides several new modes and various other extensions for the Zap
  28. text editor. In brief, these are:
  29.  
  30.   • C, C++, Java, Acorn Assembler, and Pascal source editing modes
  31.   • Colour, compilation, indenting, bracket matching, function browsers,
  32.     next/last function, swap to header, auto header file generation, improved
  33.     shift-left and right cursor (previous and next word), auto mode
  34.     detection, ensuring linefeed termination, and various commenting features
  35.     for the new modes (not all features in all modes)
  36.  
  37. Please note that ZapMJE requires Zap version 1.42 or greater to work.
  38.  
  39.  
  40. Mode specific features
  41. ==== ======== ========
  42.  
  43. Colour
  44. ------
  45.  
  46. This is currently available in the C, C++, Java, and assembler modes. Pascal
  47. will be implemented one day (when someone has told me or I have figured out
  48. the precise syntax). For C/C++/Java, the colours are as follows:
  49.  
  50.   Foreground  : Used for anything which doesn't classify below
  51.   Comments    : Anything in /* */, or after // for C++/Java
  52.   Strings     : Strings, character constants and include filenames
  53.                 (ie. anything in "", '' or, after a #include, <>)
  54.   Instructions: Reserved words (eg. switch, void)
  55.   Preprocessor: Anything on preprocessor lines not under any other category
  56.                 (including preprocessor keywords such as #define). Its use
  57.                 in Java mode is optional (MJE_PREPROSET).
  58.   Functions   : Function name in definitions, calls and macros. Not however,
  59.                 when used as a pointer
  60.   Variables   : Any other user defined word, including parameter-less macros
  61.   Numbers     : Things like 6.5!
  62.  
  63. The assembler colours are:
  64.  
  65.   Foreground  : Used for anything which doesn't classify below
  66.   Comments    : Anything after ;
  67.   Strings     : Strings and character constants (ie. anything in "" or '')
  68.   Instructions: Anything in the instruction field (first section of line
  69.                 following whitespace), plus anything else which is part of
  70.                 the instruction (eg. {, }, !). Also instruction shifts
  71.                 (eg. ASL)
  72.   Operators   : Assembler expression operators (eg. :SHL:)
  73.   Labels      : Anything in the label field (text at very start of line)
  74.   Names       : Any user defined words in the parameters of an instruction
  75.   Numbers     : Things like 2_1101
  76.  
  77. Colouring is automatic, and if you want to switch it off you will have to set
  78. all the foreground colours the same. A problem you are bound to have in 16
  79. colour modes is finding enough useable colours to display. In C they are best
  80. as all different (in assembler some of them are very closely related and
  81. hence are best coloured the same), but unfortunately there are only 5 usable
  82. colours in the normal Wimp palette. Hence the defaults are designed for 256+
  83. colour modes and I've no idea what they'll look look like in 16 colours. If
  84. using 16 colour modes, I recommend you re-define the colours in the palette
  85. to include some useable ones.
  86.  
  87. Please note that the colouring is defined to colour CORRECT source code
  88. correctly. What it does with incorrect source is arbitrary since then even
  89. the compiler/assembler will not accept it and it is hence not source code.
  90.  
  91.  
  92. Compilation
  93. -----------
  94.  
  95. This is quite powerful and is designed to cater for most situations. The way
  96. it operates is as follows (in order):
  97.  
  98. 1. Look for sourcefile.^.^.MakeFile (standard name and location for a
  99. makefile)
  100.  
  101. 2. If it is type Text (FFF) or Makefile (FE1) then pass it round as a message
  102. Data Open for either Make or AMU to pick up on. Note that it is passed round
  103. as type FE1 regardless of whether it is Text or not. This is because a lot of
  104. makefiles are typed to Text, and Make and AMU will not pick these up (but Zap
  105. will!). Also note that for AMU to intercept this message, it needs a
  106. 'filetype &FE1;' line inserted into the top section of the description file.
  107.  
  108. 3. If no task claims the message then amu is invoked from the command line in
  109. a task window. The default amu options used are '-desktop -k'. The taskwindow
  110. options used are '-display -quit'.
  111.  
  112. 4. If sourcefile.^.^.MakeFile file is not of type Text or Makefile, then it
  113. is run using Wimp_StartTask. This allows for obey files and the like to be
  114. used, giving absolute flexibility.
  115.  
  116. 5. If sourcefile.^.^.MakeFile file does not exist, then the source file is
  117. compiled/assembled direct. It cannot be passed round as a Wimp message
  118. because it is text, and so cannot be claimed by CC or whatever. Thus it is
  119. compiled/assembled in a task window along the same lines as amu if invoked
  120. above. The options used depend on the mode and are as follows:
  121.  
  122.   C      - '-IC: -throwback -LC:o.RISC_OSlib,C:o.stubs -Desktop ^'
  123.   Asm    - Assembly does not work at the moment. Makefiles are still ok
  124.            though
  125.   Pascal - '-ranprv -LC:o.Stubs -throwback -desktop ^'
  126.  
  127. 6. There is one last feature to ensure 100% flexibility. If the characters
  128. '/*+ ', ';+ ' or '(*+ ' (depending on mode) are found within the first 1k of
  129. the source file when invoking amu or compilation/assembly directly in a task
  130. window, then the following characters until the next close comment or end
  131. of line are used INSTEAD of the default options string. This means that if
  132. you don't like the default options, you can supply your own. (For instance,
  133. if you include extra libraries or want debug code generated.)
  134.  
  135. Note that the maximum length for the command issued is 255 characters,
  136. including the filename, commands and the various options. Also, NO
  137. translation is carried out in copying the options. However, when calling
  138. *TaskWindow, the command is placed in quotes - so if any were required in the
  139. options string they would have to be doubled up originally.
  140.  
  141.  
  142. There are two commands to invoke compilation; COMPILE which saves and then
  143. compiles (assuming the save was ok), and RUN which compiles without saving
  144. the current file. (These correspond to the equivalent BASIC commands.)
  145.  
  146.  
  147. Indenting
  148. ---------
  149.  
  150. This is currently only present in C, C++ and Java modes, and simply puts the
  151. requested number of extra spaces onto the indent for the line following a {,
  152. and aligns }s up with the corresponding {. The indent is set via the mode
  153. menu, and should have the value 0 to disable the feature.
  154.  
  155. Comments are optionally reindented (MJE_INDENTCOMMENTSET).
  156.  
  157. Bracket matching
  158. ------- --------
  159.  
  160. There are two types of bracket matching available, which both work on all
  161. three kinds of bracket (ie. ), }, and ]) and in all modes.
  162.  
  163. With as you type matching the cursor jumps to the corresponding open bracket
  164. for the time specified in the pause entry in the mode menu (in centiseconds)
  165. whenever you type a close bracket. The pause will be truncated if you carry
  166. on typing, and the matching can be disabled completely by setting the delay
  167. to 0.
  168.  
  169. Bracket highlighting highlights a pair of brackets when the cursor is
  170. immediately to the right of either of the pair. The brackets are highlighted
  171. by setting their background to the colour specified under 'Brackets' in the
  172. colour menu. To disable highlighting set the colour to be the same as the
  173. background colour.
  174.  
  175.  
  176. Function browsers
  177. -------- --------
  178.  
  179. This feature works on all except the C++ and Java modes, and simply provides
  180. a browser of all the function definitions in the source file. C mode
  181. correctly copes with old and new style function definitions, as well as
  182. contrived statements such as:
  183.  
  184. #ifdef __STDC__
  185. int wibble(int wobble)
  186. #else
  187. int wibble(wobble)
  188. int wobble;
  189. #endif
  190. {
  191.   ...
  192.  
  193. which are designed to work under both pcc and ANSI compilers. Assembler mode
  194. simply lists all the lines on which labels are defined. This feature is
  195. invoked with the standard command LISTFNS.
  196.  
  197.  
  198. Next/last function
  199. ---- ---- --------
  200.  
  201. These work in the same way as the function browser, but place the cursor at
  202. the definition of the next or previous function in the source file. They are
  203. invoked with MJE_NEXTFUNC and MJE_LASTFUNC respectively.
  204.  
  205.  
  206. Swap to header
  207. ---- -- ------
  208.  
  209. This moves the input focus onto the corresponding header/source file (ie.
  210. with the same leafname) for the current source/header file (assuming one
  211. exists). It also loads the file if necessary. The corresponding header file
  212. is of the form sourcefile.^.^.h.sourcefile, and the corresponding sourcefile
  213. is of the form headerfile.^.^.x.headerfile where x is c, c++, j, s, or p
  214. depending on mode. This feature is invoked with MJE_SWAPTOHEADER.
  215.  
  216.  
  217. Auto header file generation
  218. ---- ------ ---- ----------
  219.  
  220. This is only in its simple stages at the moment, but on executing
  221. MJE_GENERATEHEADER (C mode only), function prototypes will automatically be
  222. generated and appended to the respective header file (see MJE_SWAPTOHEADER).
  223. The prototypes are appended immediately after the first occurrence of the
  224. sequence '/* Auto */', deleting everything following it. If the sequence is
  225. not found in the file, then it will be appended along with the prototypes.
  226.  
  227. Currently this only deals with functions, but variables will be included at a
  228. later date. Note also that if the header file does not exist, one will NOT be
  229. created. This is done deliberately so that you can't accidentally generate
  230. unwanted header files.
  231.  
  232.  
  233. Previous and next word
  234. -------- --- ---- ----
  235.  
  236. The previous and next word commands (shift-left & shift-right) of Zap are
  237. intended for use when text editing, and as such only stop after whitespace or
  238. parentheses. This is fine for text, but totally unsuitable for program
  239. editing unless you are liberal with your spaces (I'm not). For instance,
  240. previous/next word would jump right over 'whatever=this+that/something_else;'
  241. which is not very useful. For that reason all of the extra modes have a much
  242. more powerful implementation as standard. It can be thought of as working
  243. like this:
  244.  
  245. There are 5 categories of character, classified in descending order as:
  246.  
  247.   5: Newline character
  248.   4: Letters and numbers
  249.   3: Anything else non-whitespace (ie. symbols)
  250.   2: Whitespace (space and tab)
  251.   1: Newline character
  252.  
  253. When you press shift-left or shift-right, the cursor will be moved in that
  254. direction until the classification of the next character (in the direction it
  255. is moving) is greater than that of the current character, upon which it will
  256. stop. Newline appears twice in order to ensure that the cursor will always
  257. stop on each side of it. (ie. at start & end of line).
  258.  
  259. This probably sounds quite complicated, but it is in actual fact very easy,
  260. and very intuitive to use. As an example, these are the points that the
  261. cursor would stop at:
  262.  
  263. Line:  if((char2=getchar())!=0 && char2!=line_terminator)
  264. Fwd :^ ^   ^     ^           ^ ^  ^      ^    ^          ^
  265. Back:^   ^      ^       ^     ^  ^     ^     ^          ^^
  266.  
  267.  
  268. Auto mode detection
  269. ---- ---- ---------
  270.  
  271. This is provided so that header files are loaded into the correct mode.
  272. Currently Zap can only detect mode on filetype and file name. However, header
  273. files have type text and are in a h directory, but they can be any of the
  274. five modes. Thus if header files are set to C then on loading if a C++,
  275. assembler, or Pascal comment is found as the first non-whitespace character
  276. in the file, the appropriate mode will be used instead.
  277.  
  278.  
  279. Linefeed termination
  280. -------- -----------
  281.  
  282. This quite simply ensures that there is a linefeed at the end of your file
  283. whenever you save it, in order to prevent the compiler from throwing an error
  284. and you having to re-compile for something so simple. It is functional in all
  285. four modes.
  286.  
  287.  
  288. Various commenting features
  289. ------- ---------- --------
  290.  
  291. These all work in all four modes and are:
  292.  
  293. MJE_OPENCOMMENT
  294.   This inserts the appropriate open comment text (ie. '/* ', '// ', '; ' or
  295. '(* ').
  296.  
  297. MJE_CLOSECOMMENT
  298.   Inserts appropriate close comment (' */' or ' *)' [none for C++ and
  299. assembler]).
  300.  
  301. MJE_COMMENT
  302.   This inserts both the start and end comments leaving the cursor in the
  303. middle.
  304.  
  305. MJE_IF
  306.   Inserts 'pre-processor comment'. ie. uses conditional compilation/assembly
  307. to effectively comment out the stuff ahead.. (Handy if there are comments
  308. around, since you can't nest them in C). Inserts '#if 0\n' or ' [ 1=0\n'
  309. depending on mode.
  310.  
  311. MJE_ENDIF
  312.   Finishes 'pre-processor comment'. (ie. inserts '#endif\n' or ' ]\n'.)
  313.  
  314. MJE_COMMENTLINE
  315.   Comments out line and moves onto next. (ie. inserts '/* ' & ' */', '// ',
  316. '; ', or '(* ' & ' *)' at start and end of line.)
  317.  
  318. MJE_UNCOMMENTLINE
  319.   Reverses above. (ie. removes '/* ' & ' */', '// ', '; ', or '(* ' & ' *)'
  320. if present and moves onto next line)
  321.  
  322.  
  323. Where a language has two different possible comment styles, the command
  324. MJE_COMMENTSET allows you to select the alternative one.
  325.  
  326.  
  327. Non-standard option
  328. --- -------- ------
  329.  
  330. This will not be very useful to many people, except if they lay their
  331. assembler source out the same way as I do. Basically, if enabled then on
  332. pressing tab you will be advanced to the next 'source column' rather than tab
  333. stop. It only works sensibly with Unix or column tab, and the 'source
  334. columns' are laid out as follows (using Unix tab):
  335.  
  336. Label ->------->Ins --->Operands ------>------->------->Comment
  337.  
  338. (ie. 2, 1 and 4 tab stops)
  339.  
  340. If your source looks like that, then try it, you might like it. If it doesn't
  341. then don't switch it on and no harm done. The only reason it is in there is
  342. because it is easier than disabling it for release. Also, Dominic wanted me
  343. to use the non-standard option in order to justify its existence. I bet he'll
  344. remove it now just to spite me. ;-) This feature is probably only a stop-gap
  345. until Zap supports variable tab stops properly.
  346.  
  347.  
  348. Optional behaviour
  349. -------- ---------
  350.  
  351. MJE_COMMENTSET, MJE_INDENTCOMMENTSET and MJE_PREPROSET let you toggle
  352. various optional behaviours, as noted earlier. They in general should only
  353. be used in the menus file, as supplied. Briefly, they take a word argument
  354. which has the internal mode number in the top halfword, with the bottom
  355. halfword clear.
  356.  
  357.  
  358. Note to mode authors
  359. ==== == ==== =======
  360.  
  361. Do not use any of the modes in this module as base modes - it will not work.
  362. This is due to the way that the same code is re-used for all of the modes. If
  363. you want a similar mode to these then contact me and maybe it can go in the
  364. module. Adding a new mode which takes advantage of the commenting, function
  365. finding, compiling, etc. requires nine ARM instructions and is therefore very
  366. easy and efficient. Mode specific features, such as colouring, need extra
  367. code.
  368.  
  369. ZapMJE also provides support for writing less speed critical routines in C to
  370. reduce development time for your modes. However, again these facilities are
  371. available only within the module.
  372.  
  373.  
  374. Acknowledgements
  375. ================
  376.  
  377. Thanks to Dominic for writing Zap and not even charging for it! (Though he's
  378. partly responsible for a rather large amount of damage to my 'phone bill.
  379. :-()
  380.  
  381. Thanks to Brian Scattergood for writing his Cmode which this originally came
  382. from - it made initial development a lot easier (although I did have to hack
  383. it first :-]). There's even some original (slightly modified) code left! This
  384. will have to be replaced in the course of making it work on all modes sooner
  385. or later. :-(
  386.  
  387.  
  388. Contacting
  389. ==========
  390.  
  391. Please address bug and features requests to <bugs@zap.tartarus.org> and
  392. <zap-features@zap.tartarus.org> respectively. For test versions (identified in
  393. the module help string), bugs should be sent to <betabugs@zap.tartarus.org>.
  394.  
  395. If you are unable to use email, please see the main Zap manual for a postal
  396. address to write to.
  397.  
  398.  
  399. Known mis-features
  400. ===== === ========
  401.  
  402. (These are just the important ones :-()
  403.  
  404. Assembler:
  405.  
  406.   • Assembling with no make file doesn't work
  407.   • Function finding cheats (uses search)
  408.  
  409. C/C++:
  410.  
  411.   • Auto header generation is very basic (yes, it's intentional!)
  412.   • The syntax colouring is slow with large files and multiple views of the
  413.     same file, but then when constructs such as:
  414.     #inc\
  415.     lude /* *\
  416.     / <std\
  417.     io.h>
  418.     are valid (try it, it works!), it's hardly surprising. However, this will
  419.     be improved in later versions.
  420.   • Problems with function finding:
  421.     1) Preprocessor # not at start of line not recognised
  422.     2) foo () isn't found
  423.     3) It doesn't cope with \ outside of preprocessor
  424.     These 'bugs' are due to me not knowing precisely how the C syntax worked
  425.     when I wrote it
  426.   • Typing } after this sequence causes it to get locked into a loop:
  427.      a{
  428.     a
  429.   • The header generation copies static functions into the header
  430.   • There are a multitude of bugs in the colouring, but I bet you won't find
  431.     many! :-)
  432.  
  433. Pascal:
  434.  
  435.   • Function finding cheats (like assembler)
  436.  
  437.